---
id: pinFromS3
title: ''
---

## Endpoint
https://api.decoo-cloud.cn/pinning/pinFromS3

## Description
Asynchronously pin a file from AWS S3 compatible bucket. Following Principle Of Least Privilege (PLOP), Decoo backend will download the bucket object using a presigned URL before the preset expiry date.

The basic sequence workflow is:
1. Developer calls *pinFromS3* API, with a self-hosted presigned URL generation endpoint that Decoo backend is supposed to access. A *pin job* is generated, and pin job ID is returned to the caller, which could be used to query the *pin job* status.

2. Decoo backend asynchronously picked up the *pin job*, invokes the passed endpoint to get the presigned URL.

3. Decoo backend downloads the file from S3 bucket using the presigned URL, and pins it to IPFS network (which is eventually stored to Crust network also).

4. Retrieving *pin job* result.
   - If a *pinResultCallback* endpoint is also passed when developer calling *pinFromS3*, Decoo backend will invoke that endpoint to pass pin result back.

   - Otherwise, developer could polling the *pin job* status using [pinJobs](pinning/pin-jobs.mdx) API.

:::info Guidelines to generate presigned URL
- Tencent Cloud<br/>
  https://cloud.tencent.com/document/product/436/35217

- Amazon S3<br/>
  https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html
:::

## Type
POST

## Headers
```
"Authorization": "Bearer <YOUR_API_KEY>"
```

## Body

The body of the request needs be in JSON format with following keys:

**presignedURLRequestEndpoint**<br/>
The endpoint that Decoo backend uses to request a presigned download URL for the file to pin. It should be a GET API endpoint, with necessary query parameters as part of the URL.

Developer should provide this API endpoint, and define API parameters needed to identify which bucket object to pin. For example:
```
https://<YOU_API_HOST>/getPresignedURL?bucket=<YOUR_BUCKET_NAME>&region=<YOUR_BUCKET_REGION>&key=<YOUR_FILE_OBJECT_KEY>
```


**pinResultCallbackEndpoint (optional)**<br/>

Optional endpoint to receive pinning result. If provided, the callback should accept a POST body with following keys:

- *jobId*: Id of the *pin job* generated by Decoo backend.
- *success*: Whether the file is pinned successfully. Possible values are *true* and *false*.
- *pinHash*: If pinned successfully, IPFS hash of the file generated.
- *message*: Descriptive message of the pinning result.

**decooMetadata (Optional)**

Developer can also include some metadata when pinning content to Decoo cloud. The metadata can later be used for easy querying on what you've pinned with [pinList](pinning/pin-list.mdx) request.

*decooMetadata* takes following form:
```json
{
  "name": "<A custom name. If not provided, the original name of the content (if feasible) will be used.>"
}
```

A sample request could be like:
```json
{
  "presignedURLRequestEndpoint": "https://<YOU_API_HOST>/getPresignedURL?bucket=<YOUR_BUCKET_NAME>&region=<YOUR_BUCKET_REGION>&key=<YOUR_FILE_OBJECT_KEY>",
  "pinResultCallbackEndpoint": "https://<YOUR_API_HOST>/pinResult",
  "decooMetadata": {
    "name": "<TEST_FILE>"
  }
}
```


## Response
```json
{
  "JobId": "<This is the id of the generated pin job>",
  "JobStatus": "<Current status of the pin job.  If the request was successful, the status should be 'queued'>"
}
```

## Curl Example
```sh
curl -X POST "https://api.decoo-cloud.cn/pinning/pinFromS3" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -F file=<YOUR_FILE>
  --data '{"presignedURLRequestEndpoint": "<PRESIGNED_URL_REQUEST_ENDPOINT>", "pinResultCallbackEndpoint": "<PIN_RESULT_CALLBACK_ENDPOINT>", "decooMetadata": {"name": "My File"}}'
```
